Mapping Pseudo-Objects to Java

6

6.1 Introduction

Pseudo objects are constructs whose definition is usually specified in "IDL", but whose mapping is language specified. A pseudo object is not (usually) a regular CORBA object. Often it exposed to either clients and/or servers as a process, or a thread local, programming language construct.

For each of the standard IDL pseudo-objects we either specify a specific Java language construct or we specify it as a pseudo interface.

This mapping is based on the revised version 1.1 C++ mapping.

We have chosen the option allowed in the IDL specification section 4.1.3 to define Status as void and have eliminated it for the convenience of Java programmers.

6.1.1 Pseudo Interface

The use of pseudo interface is a convenient device which means that most of the standard language mapping rules defined in this specification may be mechanically used to generate the Java. However, in general the resulting construct is not a CORBA object. Specifically it is:

not represented in the Interface Repository
no helper classes are generated
no holder classes are generated
mapped to a Java public abstract class that does not extend or inherit from any other classes or interfaces

Note: The specific definition given for each piece of PIDL may override the general guidelines above. In such a case, the specific definition takes precedence.

All of the pseudo interfaces are mapped as if they were declared in:

module org {

module omg {
module CORBA {
...
That is, they are mapped to the org.omg.CORBA Java package.

6.2 Certain Exceptions

The standard CORBA PIDL uses several exceptions, Bounds, BadKind, and InvalidName.

No holder and helper classes are defined for these exceptions, nor are they in the interface repository., However so that users can treat them as "normal exceptions" for programming purposes, they are mapped as normal user exceptions.

They are defined within the scopes that they are used. A Bounds and BadKind exception are defined in the TypeCodePackage for use by TypeCode. A Bounds exception is defined in the standard CORBA module for use by NVList, ExceptionList, and ContextList. An InvalidName exception is defined in the ORBPackage for use by ORB.

// Java

package org.omg.CORBA;

final public class Bounds

	extends org.omg.CORBA.UserException {

	public Bounds() {...}

package org.omg.CORBA.TypeCodePackage;

final public class Bounds

	extends org.omg.CORBA.UserException {

	public Bounds() {...}

final public class BadKind

	extends org.omg.CORBA.UserException {

	public BadKind() {...}

package org.omg.CORBA.ORBPackage;

final public class InvalidName

	extends org.omg.CORBA.UserException {

	public InvalidName() {...}

6.3 Environment

The Environment is used in request operations to make exception information available.

// Java code

package org.omg.CORBA;

public abstract class Environment {

	void exception(java.lang.Exception except);

	java.lang.Exception exception();

	void clear();

6.4 NamedValue

A NamedValue describes a name, value pair. It is used in the DII to describe arguments and return values, and in the context routines to pass property, value pairs.

In Java it includes a name, a value (as an any), and an integer representing a set of flags.

typedef unsigned long Flags;

typedef string Identifier;
const Flags ARG_IN = 1;
const Flags ARG_OUT = 2;
const Flags ARG_INOUT = 3;
const Flags CTX_RESTRICT_SCOPE = 15;
pseudo interface NamedValue {
readonly attribute Identifier name;
readonly attribute any value;
readonly attribute Flags flags;
};

// Java

package org.omg.CORBA;

public interface ARG_IN {

	public static final int value = 1;

public interface ARG_OUT {

	public static final int value = 2;

public interface ARG_INOUT {

	public static final int value = 3;

public interface CTX_RESTRICT_SCOPE {

	public static final int value = 15;

public abstract class NamedValue {

	public String name();

	public Any value();

	public int flags();

6.5 NVList

A NVList is used in the DII to describe arguments, and in the context routines to describe context values.

In Java it maintains a modifiable list of NamedValues.

pseudo interface NVList {

readonly attribute unsigned long count;
NamedValue add(in Flags flags);
NamedValue add_item(in Identifier item_name, in Flags flags);
NamedValue add_value(in Identifier item_name,
in any val,
in Flags flags);
NamedValue item(in unsigned long index) raises (CORBA::Bounds);
void remove(in unsigned long index) raises (CORBA::Bounds);
};

// Java

package org.omg.CORBA;

public abstract class NVList {

	public int count();

	public NamedValue add(int flags);

	public NamedValue add_item(String item_name, int flags);

	public NamedValue add_value(String item_name, Any val,

								int flags);

	public NamedValue item(int index)

					throws org.omg.CORBA.Bounds;

	public remove(int index) throws org.omg.CORBA.Bounds;

6.6 ExceptionList

An ExceptionList is used in the DII to describe the exceptions that can be raised by IDL operations.

It maintains a list of modifiable list of TypeCodes.

pseudo interface ExceptionList {

readonly attribute unsigned long count;
void add(in TypeCode exc);
TypeCode item (in unsigned long index) raises (CORBA::Bounds);
void remove (in unsigned long index) raises (CORBA::Bounds);
};

// Java

package org.omg.CORBA;

public abstract class ExceptionList {

	public int count();

	public void add(TypeCode exc);

	public TypeCode item(int index)

				throws org.omg.CORBA.Bounds;

	public void remove(int index)

				throws org.omg.CORBA.Bounds;

6.7 Context

A Context is used in the DII to specify a context in which context strings must be resolved before being sent along with the request invocation.

pseudo interface Context {

readonly attribute Identifier context_name;
readonly attribute Context parent;
Context create_child(in Identifier child_ctx_name);
void set_one_value(in Identifier propname, in any propvalue);
void set_values(in NVList values);
void delete_values(in Identifier propname);
NVList get_values(in Identifier start_scope,
in Flags op_flags,
in Identifier pattern);
};

// Java

package org.omg.CORBA;

public abstract class Context {

	public String context_name();

	public Context parent();

	public Context create_child(String child_ctx_name);

	public void set_one_value(String propname,

									 Any propvalue);

	public void set_values(NVList values);

	public void delete_values(String propname);

	public NVList get_values(String start_scpe, int op_flags,

							String pattern);

6.8 ContextList

pseudo interface ContextList {
readonly attribute unsigned long count;
void add(in string ctx);
string item(in unsigned long index) raises (CORBA::Bounds);
void remove(in unsigned long index) raises (CORBA::Bounds);
};

// Java

package org.omg.CORBA;

public abstract class ContextList {

	public int count();

	public void add(String ctx);

	public String item(int index)

		throws org.omg.CORBA.Bounds;

	public void remove(int index)

		throws org.omg.CORBA.Bounds;

6.9 Request

pseudo interface Request {
readonly attribute Object target;
readonly attribute Identifier operation;
readonly attribute NVList arguments;
readonly attribute NamedValue result;
readonly attribute Environment env;
readonly attribute ExceptionList exceptions;
readonly attribute ContextList contexts;
attribute Context ctx;
any add_in_arg();
any add_named_in_arg(in string name);
any add_inout_arg();
any add_named_inout_arg(in string name);
any add_out_arg();
any add_named_out_arg(in string name);
void set_return_type(in TypeCode tc);
any return_value();
void invoke();
void send_oneway();
void send_deferred();
void get_response();
boolean poll_response();
};

// Java

package org.omg.CORBA;

public abstract class Request {

	Object target();

	String operation();

	NVList arguments();

	NamedValue result();

	Environment env();

	ExceptionList exceptions();

	ContextList contexts();

	Context ctx();

	void ctx(Context c);

	Any add_in_arg();

	Any add_named_in_arg(String name);

	Any add_inout_arg();

	Any add_named_inout_arg(String name);

	Any add_out_arg();

	Any add_named_out_arg(String name);

	void set_return_type(TypeCode tc);

	Any return_value();

	void invoke();

	void send_oneway();

	void send_deferred();

	void get_response();

	boolean poll_response();

6.10 ServerRequest and Dynamic Implementation

pseudo interface ServerRequest {
Identifier op_name();
Context ctx();
void params(in NVList parms);
void result(in Any res);
void except(in Any ex);
} ;

// Java

package org.omg.CORBA;

public abstract class ServerRequest {

	String op_name();

	Context ctx();

	void params(NVList parms);

	void result(Any a);

	void except(Any a);

The DynamicImplementation interface defines the interface such a dynamic server is expect to implement. Note that it inherits from the base class for stubs and skeletons (see Section 8.5.2, "Portable ObjectImpl").

// Java

package org.omg.CORBA;

public abstract class DynamicImplementation

		extends org.omg.CORBA.portable.ObjectImpl {

	public void invoke(org.omg.CORBA.ServerRequest request);

6.11 TypeCode

The deprecated parameter and param_count methods are not mapped.

enum TCKind {

tk_null, tk_void,
tk_short, tk_long, tk_ushort, tk_ulong,
tk_float, tk_double, tk_boolean, tk_char,
tk_octet, tk_any, tk_TypeCode, tk_Principal, tk_objref,
tk_struct, tk_union, tk_enum, tk_string,
tk_sequence, tk_array, tk_alias, tk_except,
tk_longlong, tk_ulonglong, tk_longdouble,
tk_wchar, tk_wstring, tk_fixed
};

// Java

package org.omg.CORBA;

public final class TCKind {

	public static final int _tk_null = 0;

	public static final

		TCKind tk_null = new TCKind(_tk_null);

	public static final int _tk_void = 1;

		TCKind tk_void = new TCKind(_tk_void);

	public static final int _tk_short = 2;

		TCKind tk_short = new TCKind(_tk_short);

	public static final int _tk_long = 3;

		TCKind tk_long = new TCKind(_tk_long);

	public static final int _tk_ushort = 4;

		TCKind tk_ushort = new TCKind(_tk_ushort);

	public static final int _tk_ulong = 5;

		TCKind tk_ulong = new TCKind(_tk_ulong);

	public static final int _tk_float = 6;

		TCKind tk_float = new TCKind(_tk_float);

	public static final int _tk_double = 7;

		TCKind tk_double = new TCKind(_tk_double);

	public static final int _tk_boolean = 8;

		TCKind tk_boolean = new TCKind(_tk_boolean);

	public static final int _tk_char = 9;

		TCKind tk_char = new TCKind(_tk_char);

	public static final int _tk_octet = 10;

		TCKind tk_octet = new TCKind(_tk_octet);

	public static final int _tk_any = 11;

		TCKind tk_any = new TCKind(_tk_any);

	public static final int _tk_TypeCode = 12;

		TCKind tk_TypeCode = new TCKind(_tk_TypeCode);

	public static final int _tk_Principal = 13;

		TCKind tk_Principal = new TCKind(_tk_Principal);

	public static final int _tk_objref = 14;

		TCKind tk_objref = new TCKind(_tk_objref);

	public static final int _tk_stuct = 15;

		TCKind tk_stuct = new TCKind(_tk_stuct);

	public static final int _tk_union = 16;

		TCKind tk_union = new TCKind(_tk_union);

	public static final int _tk_enum = 17;

		TCKind tk_enum = new TCKind(_tk_enum);

	public static final int _tk_string = 18;

		TCKind tk_string = new TCKind(_tk_string);

	public static final int _tk_sequence = 19;

		TCKind tk_sequence = new TCKind(_tk_sequence);

	public static final int _tk_array = 20;

		TCKind tk_array = new TCKind(_tk_array);

	public static final int _tk_alias = 21;

		TCKind tk_alias = new TCKind(_tk_alias);

	public static final int _tk_except = 22;

		TCKind tk_except = new TCKind(_tk_except);

	public static final int _tk_longlong = 23;

		TCKind tk_longlong = new TCKind(_tk_longlong);

	public static final int _tk_ulonglong = 24;

		TCKind tk_ulonglong = new TCKind(_tk_ulonglong);

	public static final int _tk_longdouble = 25;

		TCKind tk_longdouble = new TCKind(_tk_longdouble);

	public static final int _tk_wchar = 26;

		TCKind tk_wchar = new TCKind(_tk_wchar);

	public static final int _tk_wstring = 27;

		TCKind tk_wstring = new TCKind(_tk_wstring);

	public static final int _tk_fixed = 28;

		TCKind tk_fixed = new TCKind(_tk_fixed);

	public int value() {...}

	private TCKind(int) {...}

pseudo interface TypeCode {
exception Bounds {};
exception BadKind {};
// for all TypeCode kinds
boolean equal(in TypeCode tc);
TCKind kind();
// for objref, struct, union, enum, alias, and except
RepositoryID id() raises (BadKind);
RepositoryId name() raises (BadKind);
// for struct, union, enum, and except
unsigned long member_count() raises (BadKind);
Identifier member_name(in unsigned long index)
raises (BadKind, Bounds);
// for struct, union, and except
TypeCode member_type(in unsigned long index)
raises (BadKind, Bounds);
// for union
any member_label(in unsigned long index) raises (BadKind, Bounds);
TypeCode discriminator_type() raises (BadKind);
long default_index() raises (BadKind);
// for string, sequence, and array
unsigned long length() raises (BadKind);
TypeCode content_type() raises (BadKind);
}

// Java

package org.omg.CORBA;

public abstract class TypeCode {

	// for all TypeCode kinds

	boolean equal(TypeCode tc);

	TCKind kind();

	// for objref, struct, unio, enum, alias, and except

	String id() throws TypeCodePackage.BadKind;

	String name() throws TypeCodePackage.BadKind;

	// for struct, union, enum, and except

	int member_count() throws TypeCodePackage.BadKind;

	String member_name(ing index)

			throws TypeCodePackage.BadKind;

	// for struct, union, and except

	TypeCode member_type(int index)

			throws TypeCodePackage.BadKind,

						TypeCodePackage.Bounds;

	// for union

	Any member_label(int index)

			throws TypeCodePackage.BadKind,

						TypeCodePackage.Bounds;

	TypeCode discriminator_type()

			throws TypeCodePackage.BadKind;

	int default_index() throws TypeCodePackage.BadKind;

	// for string, sequence, and array

	int length() 			throws TypeCodePackage.BadKind;

	TypeCode content_type() 			throws TypeCodePackage.BadKind;

6.12 ORB

Issue - create_named_value() is incorrect in the CORBA spec. We have used the correct definition here. It is indicated as a change to CORBA 2.0

The UnionMemeberSeq, EnumMemberSeq, and StructMemberSeq typedefs are real IDL and bring in the Interface Repository. Rather than tediously list its interfaces, and other assorted types, suffice it to say that it is all mapped following the rules for IDL set forth in this specification in Chapter 5, "Mapping IDL to Java".

StructMember[], UnionMember[], EnumMember[]

pseudo interface ORB {

// Java signatures

//	public static ORB init(Strings[] args, Properties props);

//	public static ORB init(Applet app, Properties props);

//	public static ORB init();

// abstract protected void set_parameters(String[] args,

//										java.util.Properties props);

// abstract protected void set_parameters(Applet app,

//										java.util.Properties props);

}

// Java

package org.omg.CORBA;

public abstract class ORB {

	String[] list_initial_services();

	org.omg.CORBA.Object resolve_initial_references(

		String object_name)

		throws org.omg.CORBA.ORBPackage.InvalidName;

	String object_to_string(org.omg.CORBA.Object obj);

	org.omg.CORBA.Object string_to_object(String str);

	NVList create_list(int count);

	NVList create_operation_list(OperationDef oper);

	NamedValue create_named_value(String name,

										  Any value,

										  int flags);

	ExceptionList create_exception_list();

	ContextList create_context_list();

	Context get_default_context();

	Environment create_environment();

	void send_multiple_requests_oneway(Request[] req);

	void sent_multiple_requests_deferred(Request[] req);

	boolean poll_next_response();

	Request get_next_response();

	// typecode creation

	TypeCode create_struct_tc(									String id,

										String name,

										StructMember[] members);

	TypeCode create_union_tc(									String id,

										String name,

										TypeCode discriminator_type,

										UnionMember[] members);

	TypeCode create_enum_tc(									String id,

										String name,

										EnumMember[] members);

	TypeCode create_alias_tc(									String id,

										String name,

										TypeCode original_type);

	TypeCode create_exception_tc(	String id,

										String name,

										StructMember[] members);

	TypeCode create_interface_tc(	String name

										String name);

	TypeCode create_string_tc(									int bound);

	TypeCode create_wstring_tc(									int bound);

	TypeCode create_sequence_tc(int bound,

										TypeCode element_type);

	TypeCode create_recursive_sequence_tc(int bound,

										int offset);

	TypeCode create_array_tc(									int length,

										TypeCode element_type);

	Current get_current();

	// additional methods for IDL/Java mapping

	TypeCode get_primitive_tc(									TCKind tcKind);

	Any create_any();

	org.omg.CORBA.portable.OutputStream

										create_output_stream();

	void connect(org.omg.CORBA.Object obj);

	void disconnect(org.omg.CORBA.Object obj);

	// additional static methods for ORB initialization

	public static ORB init(Strings[] args, Properties props);

	public static ORB init(Applet app, Properties props);

	public static ORB init();

6.13 CORBA::Object

The IDL Object type is mapped to the org.omg.CORBA.Object and org.omg.CORBA.ObjectHelper classes as shown below.

The Java interface for each user defined IDL interface extends org.omg.CORBA.Object, so that any object reference can be passed anywhere a org.omg.CORBA.Object is expected.

// Java

package org.omg.CORBA;

public interface Object {

	boolean _is_a(String Identifier);

	boolean _is_equivalent(Object that);

	boolean _non_existent();

	int _hash(int maximum);

	org.omg.CORBA.Object _duplicate();

	void _release();

	ImplementationDef _get_implementation();

	InterfaceDef _get_interface();

	Request _request(String s);

	Request _create_request(Context ctx,

									String operation,

									NVList arg_list,

									NamedValue result);

	Request _create_request(Context ctx,

									String operation,

									NVList arg_list,

									NamedValue result,

									ExceptionList exclist,

									ContextList ctxlist);

6.14 Current

pseudo interface Current {
}

// Java

public abstract class Current

		extends org.omg.CORBA.portable.ObjectImpl {

6.15 Principal

pseudo interface Principal {
attribute sequence<octet> name;
}

// Java

public abstract class Principal {

	byte[] name();

	void name(byte[] name);